docs(lstk `hotfix`): update CLI reference to v0.23.0 by gtsiolis · Pull Request #912 · localstack/localstack-docs

gtsiolis · 2026-09-02T10:33:25Z

Motivation

The lstk CLI reference reflected roughly v0.20.x, while the latest release is v0.23.0. This catches up the full v0.21.0 → v0.23.0 backlog — fixing claims that no longer match the CLI and documenting features that shipped in that range — and folds in the corrections from the three superseded doc-sync PRs (#833, #850, #877) that were closed when the docs were restructured.

Reference surfaces in scope

There are no shared lstk components, so content lives directly in the pages.

AWS — the canonical multi-page reference under src/content/docs/aws/developer-tools/running-localstack/lstk/: index.mdx, authentication.md, configuration.mdx, cloud-and-iac-commands.md, snapshots.md, automation.mdx, lifecycle-commands.md, faq-and-troubleshooting.md, setup-and-maintenance.md.
Azure — src/content/docs/azure/developer-tools/lstk.mdx (the single-page reference), brought to the same accuracy.

What changed

v0.21.0 → v0.22.2

Corrections (stale / no longer accurate):

Auth token resolution order was inverted. LOCALSTACK_AUTH_TOKEN takes precedence over a keyring token (v0.21+); the docs said the opposite and told users to lstk logout first. Fixed on both pages (resolution list, admonition, env-var table).
"Port 443 already in use" described a hard failure. The auto-added 443 is dropped with a warning (HTTPS stays on 4566); only an explicitly-listed port is a hard requirement. Rewrote it (and fixed the Azure page's example, which used type = "aws").
"Docker is not running" named only Colima/OrbStack → now the full runtime set.
Azure snapshots — experimental (same warning as Snowflake), not "not yet supported".

Additions (previously undocumented):

--endpoint-url / LSTK_ENDPOINT_URL — new "Targeting an external emulator" section, plus global-options and env-var rows and cross-references.
snapshot versions subcommand and pod:<name>:<version> refs on load/show.
lstk aws --account leading flag, with a "Selecting the account" section.
container_name and expose_ports config fields.
Container runtime discovery — full runtime set, resolution order (DOCKER_HOST → DOCKER_CONTEXT/CLI context → Linux socket → probe → SDK default), and the tailored start-command hint.
Binary self-update SHA-256 checksum verification; lstk az consuming its own flags; lstk aws completion note.

v0.23.0 delta

--json is now supported by start and status (previously only stop/reset/update). Updated the global-options table and the "Structured output" section on both pages, and added per-command --json notes to start (flat data object) and status (data.emulators[], plus the --no-resources toggle and --json --endpoint-url targeting). AWS-only resource details are labeled as such on the shared Azure page.

Snowflake

There is no lstk reference page under src/content/docs/snowflake/ on main yet — it is being introduced by #910. There is nothing to correct there; these same fixes should be folded into #910 (and into the Azure restructure #909) since both are copies of this shared content.

Needs a human decision

The Azure (#909) and Snowflake (#910) lstk doc restructures split this same content into the multi-page layout. Whichever of these merges first, the other must carry these corrections forward. The Azure edits here overlap #909 — coordinate on merge order.

Review

Recommended: mostly additive reference content verified against the v0.23.0 CLI surface, but the auth-token precedence reversal and the Port 443 drop-with-warning reframing are user-facing behavior corrections worth a second look.

Closes DOC-433

Cc @localstack/devx for visibility and any corrections.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cloudflare-workers-and-pages · 2026-09-02T10:33:59Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`64c9d0d`
Status:	✅ Deploy successful!
Preview URL:	https://bc4895ee.localstack-docs.pages.dev
Branch Preview URL:	https://claude-hopeful-babbage-21z8t.localstack-docs.pages.dev

View logs

gtsiolis · 2026-09-02T10:35:43Z

The one red check here is Validate Refs, which is the repo's branch-naming gate (feature-branch-only-to-main.yml): a PR into main must have a head branch named aws-docs-* or snowflake-docs-*. This branch is claude/hopeful-babbage-21z8t2, so it fails the gate.

This is unrelated to the docs changes themselves — Cloudflare Pages built the site successfully and the preview renders. The same check is red on the sibling in-flight lstk doc PRs (#909, #910), which target main from doc-429-*/doc-430-* branches for the same reason, so this isn't specific to this PR's content.

I can't rename the branch to satisfy the gate from here (the branch name is fixed for this change). A maintainer can either merge via the usual docs flow that bypasses this check, or re-target/rename onto an aws-docs-* feature branch. Flagging rather than working around it.

Generated by Claude Code

…acement Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…nto claude/hopeful-babbage-21z8t2 # Conflicts: # src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gtsiolis · 2026-09-02T11:16:32Z

Update: expanded scope to the Azure page + folded in the superseded PRs

Since the last round, this PR now also brings azure/developer-tools/lstk.mdx to v0.22.2 accuracy, and folds in the corrections from the three closed doc-sync PRs (#833, #850, #877) that never merged. The PR description has been rewritten to match.

Applied to both the AWS multi-page reference and the Azure page:

Auth-token precedence reversed (LOCALSTACK_AUTH_TOKEN wins over the keyring).
--endpoint-url / LSTK_ENDPOINT_URL — new "Targeting an external emulator" section + table rows.
snapshot versions subcommand and pod:<name>:<version> refs.
lstk aws --account + "Selecting the account".
container_name and expose_ports config fields.
Container runtime discovery (full runtime set, resolution order, tailored start hint).
"Port 443 already in use" rewritten (drop-with-warning, not fatal; Azure example corrected to type = "azure").
"Docker is not running" now names the full runtime set.
Self-update SHA-256 checksum; lstk az consuming its own flags; lstk aws <TAB> completion note.
Azure snapshots noted as experimental (not "unsupported").

Snowflake: there's no lstk page under snowflake/ on main yet (it's being added by #910), so nothing to correct there — these same fixes should land in #910 and in the Azure restructure #909, both of which are copies of this shared content.

Review threads: all three resolved — the --account wording (fixed) and the two AWS/Azure/Snowflake-scope questions (mentions kept intentionally, now consistent across both pages).

CI: Cloudflare Pages builds green on the current head; the only red is the Validate Refs branch-naming gate, which the docs-team PRs trip too and which doesn't re-run on pushes.

Cc @localstack/devx for visibility and any corrections.

Generated by Claude Code

mmaureenliu

Looks good in general. Minor fixes required. I assume tech details are correct after @anisaoshafi has done the eng review.

mmaureenliu · 2026-09-02T12:49:25Z

 `lstk setup aws` works non-interactively — it writes the profile with defaults and needs `--force` only to overwrite a conflicting `localstack` profile.
 :::

+## Targeting an external emulator


I think this belongs to the "Cloud and IaC Commands" section as this option is quite important for local dev use case. @peter-smith-phd what do you think?

It lives in the global-options table because --endpoint-url is a persistent/global flag that applies across many commands (aws, az, the IaC tools, status, reset, snapshot), not just the IaC ones — and the full "Targeting an external emulator" section is right below it. I've also cross-referenced it from the Cloud & IaC page's intro note so it's discoverable from there. Happy to move the detailed section into Cloud & IaC (or duplicate a short callout there) if you and @peter-smith-phd prefer that placement — leaving this open for your call rather than restructuring unilaterally.

Generated by Claude Code

mmaureenliu · 2026-09-02T14:16:30Z

@quetzalliwrites should this one share the same components as the aws lstk docs?

and for Snowflake

Context for this one: there are no shared lstk components today — the AWS multi-page reference and this Azure single page each carry their own copy of the content (they're near-identical because lstk is one CLI). The Azure restructure #909 (by @quetzalliwrites) splits this single page into the same multi-page layout as AWS. My edits here are just keeping the live single page accurate for v0.22.2 in the meantime; if #909 lands first, these same corrections should be carried into it. Whether to factor the shared content into real shared components is a good call for that restructure — deferring to you and @quetzalliwrites.

Generated by Claude Code

mmaureenliu · 2026-09-02T14:18:16Z

@peter-smith-phd do you think it makes sense to apply your update to the first FAQ answer directly in this PR?

…imental) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gtsiolis · 2026-09-03T10:50:16Z

Update: extended to v0.23.0

lstk v0.23.0 shipped, so this PR now catches up the reference to that tag (the range is v0.21.0 → v0.23.0). Retitled and description updated; DOC-433 renamed to match.

The only user-facing delta since v0.22.2 is structured --json output landing on start and status (previously stop/reset/update only). Applied to both the AWS multi-page reference and the Azure page:

Global-options --json row and the "Structured output" section now list start, stop, status, reset, update.
Added a per-command --json note to start (flat data object) and status (data.emulators[], the --no-resources toggle, and --json --endpoint-url targeting). Resource details are labeled AWS-only on the shared Azure page.

The rest of v0.22.2 → v0.23.0 is deps bumps, a dev sandbox script, an internal PTY-input fix, and the internal IAC error-code group — nothing that changes the documented CLI surface.

The two open review threads (the --endpoint-url placement question and the shared-components question) are untouched by this and still awaiting your call.

Cc @localstack/devx for visibility and any corrections.

Generated by Claude Code

docs(lstk): update CLI reference to v0.22.2

fd84986

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gtsiolis requested review from HarshCasper, quetzalliwrites and remotesynth as code owners September 2, 2026 10:33

gtsiolis added the hotfix docs label Sep 2, 2026 — with Claude

anisaoshafi reviewed Sep 2, 2026

View reviewed changes

anisaoshafi and others added 4 commits September 2, 2026 12:56

Fix inaccurate statement on aws --account

da5d692

docs(lstk): fold in runtime discovery, port 443, checksum, account pl…

c8ad05a

…acement Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge remote-tracking branch 'origin/claude/hopeful-babbage-21z8t2' i…

c6024d5

…nto claude/hopeful-babbage-21z8t2 # Conflicts: # src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md

docs(lstk): apply the same v0.22.2 corrections to the Azure lstk page

800fe40

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

mmaureenliu requested changes Sep 2, 2026

View reviewed changes

gtsiolis and others added 2 commits September 3, 2026 08:44

docs(lstk): Azure does not support snapshots (only Snowflake is exper…

610128e

…imental) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(lstk): document --json for start and status (v0.23.0)

64c9d0d

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gtsiolis changed the title ~~docs(lstk hotfix): update CLI reference to v0.22.2~~ docs(lstk hotfix): update CLI reference to v0.23.0 Sep 3, 2026

Navigation Menu

Uh oh!

docs(lstk `hotfix`): update CLI reference to v0.23.0 - #912

docs(lstk `hotfix`): update CLI reference to v0.23.0#912
gtsiolis wants to merge 7 commits into
mainfrom
claude/hopeful-babbage-21z8t2

gtsiolis commented Sep 2, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 2, 2026 •

edited

Loading

Uh oh!

gtsiolis commented Sep 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gtsiolis commented Sep 2, 2026

Uh oh!

mmaureenliu left a comment

Uh oh!

mmaureenliu Sep 2, 2026

Uh oh!

gtsiolis Sep 3, 2026

Uh oh!

Uh oh!

mmaureenliu Sep 2, 2026

Uh oh!

mmaureenliu Sep 2, 2026

Uh oh!

gtsiolis Sep 3, 2026

Uh oh!

mmaureenliu commented Sep 2, 2026

Uh oh!

gtsiolis commented Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

gtsiolis commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Reference surfaces in scope

What changed

v0.21.0 → v0.22.2

v0.23.0 delta

Snowflake

Needs a human decision

Review

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying localstack-docs with Cloudflare Pages

Uh oh!

gtsiolis commented Sep 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gtsiolis commented Sep 2, 2026

Update: expanded scope to the Azure page + folded in the superseded PRs

Uh oh!

mmaureenliu left a comment

Choose a reason for hiding this comment

Uh oh!

mmaureenliu Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmaureenliu Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mmaureenliu Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

mmaureenliu commented Sep 2, 2026

Uh oh!

gtsiolis commented Sep 3, 2026

Update: extended to v0.23.0

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gtsiolis commented Sep 2, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Sep 2, 2026 •

edited

Loading